Montage is a general astronomical image toolkit with facilities for reprojection, background matching, coaddition and visualization. It can be used as a set of command-line tools (Linux, OS X and Windows), C library calls (Linux and OS X) and as Python binary extension modules.
Montage source code can be downloaded from GitHub ( https://github.com/Caltech-IPAC/Montage ). The Python package can be installed from PyPI ("pip install MontagePy"). See http://montage.ipac.caltech.edu/ for more information.
A large percentage of the Montage modules focus on processing a set of images (often retrieved from a mission archive); projecting them to a common frame, adjusting their background levels as a set, and coadding them into a mosaic.
Starting with archive access, this mosaicking sequence uses the following modules:
This page is focused on the details of one of these modules: mAdd. For a broader context, please see Building a Mosaic with Montage or the one shot version if you just want to see the commands.
Note: The MontagePy python package has no external dependencies. We include other utilities on this page to aid in visualizing MontagePy package results.
from MontagePy.main import mAdd, mViewer
help(mAdd)
mAdd is the tail end of the mosaicking process. At this point we have a set of reprojected (and often background-matched) images and have generated a metadata table listing them all. The last step is to coadded them all, properly weighting things like fractional pixels, to produce the final mosaic.
The basic inputs are the images themselves (the path to them and the table of metadata), the header template for the output (which by now should match, except for integer pixel offsets, the headers in each image), and the name of the desired output image file.
mAdd has a few extra controls that can be used to tell it whether to "shrink-wrap" the mosaic (remove empty border pixel areas) and whether the input images have associated "area" images (for proper weighting of fractional pixel coaddition). In addition, the user has the option of overriding the default coaddition mode (mean) and instead return the median or just the count of the input pixels.
See previous steps in the process for details on the header template.
rtn = mAdd("M17/corrected", "M17/cimages.tbl", "M17/M17.hdr", "work/M17/mosaic.fits")
print(rtn)
Here is one of the input (reprojected, background-matched) images:
from IPython.display import Image
rtn = mViewer('-ct 1 -gray M17/corrected/hdu0_2mass-atlas-990502s-j1430080.fits \
-2s max gaussian-log -out work/M17/hdu0_2mass-atlas-990502s-j1430080_add.png',
'', mode=2)
print(rtn)
Image(filename='work/M17/hdu0_2mass-atlas-990502s-j1430080_add.png')
and here is the mosaic (the above image contains the eastern part of the nebulosity):
rtn = mViewer('-color black -imginfo M17/rimages.tbl \
-ct 1 -gray M17/mosaic.fits -2s max gaussian-log \
-out work/M17/mosaic_add.png',
'', mode=2)
print(rtn)
Image(filename='work/M17/mosaic_add.png')
If mAdd encounters an error, the return structure will just have two elements: a status of 1 ("error") and a message string that tries to diagnose the reason for the error.
For instance, if the user asks for a table that doesn't exist:
rtn = mAdd("M17/corrected", "M17/unknown.tbl", "M17/M17.hdr", "work/M17/mosaic.fits")
print(rtn)
mAdd can also be run as a command-line tool in Linux, OS X, and Windows:
Usage: mAdd [-d level] [-p imgdir] [-n(o-areas)] [-a mean|median|count] [-e(xact-size)] [-s statusfile] images.tbl template.hdr out.fits
If you are writing in C/C++, mAdd can be accessed as a library function:
/*-***********************************************************************/
/* */
/* mAdd */
/* */
/* Montage is a set of general reprojection / coordinate-transform / */
/* mosaicking programs. Any number of input images can be merged into */
/* an output FITS file. The attributes of the input are read from the */
/* input files; the attributes of the output are read a combination of */
/* the command line and a FITS header template file. */
/* */
/* This module, mAdd, reads sets of flux / area coverage images */
/* (the output of mProject) which have already been projected / */
/* resampled onto the same pixel space. The fluxs, scaled by total */
/* input area, are then coadded into a single output composite. */
/* */
/* char *path Directory containing files to be coadded */
/* char *tblfile Table file list of reprojected files to */
/* coadd */
/* char *template_file FITS header file used to define the desired */
/* output */
/* char *outfile Final mosaic FITS file */
/* */
/* int shrink Shrink-wrap to remove blank border areas */
/* int haveAreas Area files exist for weighting the coadd */
/* int coadd Image stacking: 0 (MEAN), 1 (MEDIAN) */
/* 2 (COUNT), 3 (SUM) */
/* */
/* int debug Debugging output level */
/* */
/*************************************************************************/
struct mAddReturn *mAdd(char *path, char *tblfile, char *template_file, char *outfile,
int shrink, int haveAreas, int coadd, int debugin)
Return Structure
struct mAddReturn
{
int status; // Return status (0: OK, 1:ERROR)
char msg [1024]; // Return message (for error return)
char json[4096]; // Return parameters as JSON string
double time; // Run time (sec)
};